Repository navigation
feat(confsearch): search engine, checkpoint/resume, results and exports (P2) - #64
Conversation
Tracking: #61 (spec revision 4, phase P1) Part of the MD-based configuration search feature. What was missing: mliport/confsearch/ did not exist, so nothing could prepare starts, describe a minimum, or deduplicate quench results. What this adds (calculator-free, synthetic-structure testable): - options.py: frozen ConfsearchOptions with every section 12.3 cross-key rule (mode A/B exclusivity, exact integer step conversions with nearest valid values, break > bond scale, binwidth <= sigma/2, v1 non-goals rejected by name), index_spec.py: the 0-based "0,5,7-9" parser with compression. - regions.py: A/S/F/R resolution, FixScaled/FixCom rejection, cs_fix_below, the +z surface convention, slab contiguity, one-sided adsorption, non-ionic adsorbate connectivity, the H/timestep gate and the section 7.2 mobile sets. - graphs.py: covalent graphs from ase.data.covalent_radii, ionic exclusion, the MD break-scale check, chemisorption flags, slab-rearrangement flags and the section 8.2 status rules in order. - fingerprint.py: focused Oganov-Valle with ASE's discretisation (spec 9.2 revision 3): nbins = ceil(rcut/Delta), bin radius (k+1)Delta, erf bin smearing renormalised to 1, 4 pi r^2 Delta and N_beta/V normalisation, ordered species keys and the section 9.2 weights. - registry.py: delta-E AND (G OR D) matching (spec 9.3 revision 4), the direct geometric identity G with cs_dedup_geom_tol (disabled and recorded when F is empty), smallest (not G, D) selection, per-status registries, representative update and the section 9.5 consolidation pass. - placement.py: centroiding, Shoemake rotations, contact and anchored placement solved by bisection on element-pair covalent-radii ratios, anchor targets, per-reason rejection counts and the recorded placement provenance. Deviations from the letter of section 9.2, both required by section 9.2 itself and documented in the module docstring: - self-image pairs are enumerated explicitly because ASE's neighbor_list returns an orientation-dependent subset of them (48 vs 72 pairs on a 4x4x20 A slab before/after a rigid rotation, while the 350 cross pairs are identical); - pair distances are rounded to 1e-9 A before the bin division because a distance at a decimal multiple of Delta (e.g. a 0.96 A O-H bond) otherwise flips its whole 21-bin smearing window under a rigid rotation. The strict ASE known-answer tests still pass to 1e-10 on non-boundary geometries (per-bin arrays, F_ab == F_ba, collapsed D), and scipy/matplotlib were added to the dev extra so they run in CI instead of skipping. Calibration (spec 13.2 revision 4, geometry-labelled pairs on the repository's LGPS structure, pinned as a regression test): same basin 25 pairs (G), 11 documented false splits (0.20-0.5 A); distinct sites/conformers 63 pairs, min D = 8.5e-4 at sigma = 0.20; equivalent pairs (rigid slab map + CH3 permutation) all merge (D ~ 0). Shipped defaults: cs_fp_sigma = 0.20, cs_dedup_fp_tol = 0.0004 (zero false merges with a factor-2 margin), cs_dedup_geom_tol = 0.20 A. DATA IMPACT: no scientific record invalidated (no existing workflow changed). New defaults are recorded here and in the calibration test; the P2 engine will re-run the same sweep with real quenches at cs_quench_fmax. Full suite on CPU: 1555 passed, 33 skipped.
hydrogen1222
left a comment
There was a problem hiding this comment.
Review (spec rev 5) — P2: changes requested
The cycle (MB over mobile DOF with zero fixed momenta, Langevin hold, linear ramp via set_temperature, snapshot quenches, Metropolis with aligned draws), RNG streams and checkpoint/restore are correct. Requested changes, most important first:
1. Refinement / ranking (§10.1, §10.3) — blocking. In results.build_results (~L383–430):
ranked_energiesuses the refinement energy unconditionally, also when the refinement isquench_failed(energy may be NaN), not converged, or changed status (e.g. nowreacted/desorbed). Spec: an unconverged refinement keeps the quench result and is flagged; a status change must be honoured (a refined minimum that is no longer rankable leaves the ranking, with a record why).- Ranking entries and export directories follow quench-energy order (
rankable), not refined energy, sotop/rank_001is not necessarily the lowest refined structure. - The refined set is not re-deduplicated (§10.3), so two uniques that refine into the same minimum are both exported.
best_energyand the export window mix refined (fmax 0.02) and unrefined (fmax 0.05) energies; spec says never interleave them. Rank refined entries among themselves; report unrefined separately.
Tests: a synthetic case where refinement (a) lowers the order of two candidates, (b) merges two candidates, (c) fails, (d) changes status.
2. Aborted MD frames are quenched (§7.3 step 9). engine.py ~L641 appends exc.frame to snapshots. A force-abort frame (|F| > 20 eV/Å) or a non-finite frame is then quenched, and an integrity-abort frame is quenched twice (it was appended at L607 before _check_md_integrity raised). This inflates reacted/quench_failed counts, which feed the §8.5 warnings and the discovery curve. Quench only snapshots taken before the stop; keep the abort frame in the raw trajectory only.
3. End-of-cycle integrity check missing (§7.3 step 7). _check_md_integrity runs only at snapshot steps; also run it on the final frame.
4. quench() can crash the search. quench.py L124 calls work.get_potential_energy() outside any try; a calculator that raises on a bad geometry turns a quench_failed outcome into an uncaught exception. Wrap it.
5. Diagnostics definitions.
_baseline_report: "top-K never reached by any start quench" must mean unique minima with no member whose origin isstart— not "representative not from start and below the baseline best".best_first_found_fraction(L271) andfirst_found_fraction(L152) use the representative'squench_index; usefirst_found_quench_index.
6. Missing outputs (§11.1). minima/all_minima.extxyz (every quench result, all statuses) and minima/registry.json are never written; members' geometries are therefore lost except representatives. Write them.
🤖 Generated with Claude Code
Generated by Claude Code
… §5.2) Tracking: #61 (spec revision 5, PR #63 review) Addresses review items 1-3 on #63. - Anchored placement now solves the height against the anchor's **partner set**: the non-ionic slab atoms by default, or exactly the `cs_place_anchor_targets` elements when that option is set. Previously the minimum `q` was taken over every slab atom, so an anchor O could be placed at 1.1x the O+Li radii sum from a lithium: an ionic contact that §8.1/§8.2 then classify as physisorbed, i.e. the "chemisorption-first" start was not chemisorbed. `anchor_partner_indices()` fails closed when the slab has no partner at all (all-ionic slab without targets). - Tests: a Li-terminated slab must bond the O anchor to a sulfur (and the recomputed min q over non-ionic atoms equals `cs_place_anchor_scale`), `cs_place_anchor_targets="Li"` is the explicit opt-in to an ionic partner, and an all-ionic slab without targets is refused. - `fingerprint.py` docstring rewritten for revisions 3-5: ASE discretisation, the withdrawn pre-rev-3 point-sampled formula, the strict per-bin 1e-10 known-answer test that never skips (ASE 3.26 oracle when the ASE 3.29 shim is in place), and the self-image paragraph reworded as a cutoff-boundary effect (images at exactly rcut) rather than an ASE defect. - `placement.py` documents that `min q` is monotone except in the descent branch, where atoms can end up slightly below the slab top. - `options.py` and the calibration test now state the P1 calibration's known limitations (bulk-cell geometry, perturbations instead of quenches, exact rigid images) and point at a real-slab/real-model recalibration as a P5 validation item. DATA IMPACT: no scientific record invalidated. Placement semantics change only for anchored starts on slabs containing ionic species; the shipped defaults and the fingerprint/dedup behaviour are unchanged. Full confsearch suite on CPU: 112 passed.
…puts (spec rev 5 §10/§11.1) Tracking: #61 (spec revision 5, PR #64 review) Addresses all six review items on #64. Ranking and refinement (spec 10.1/10.3): - a refinement replaces the quench result only when it converged **and** its classification is still rankable; an unconverged refinement keeps the quench result and is flagged (`refinement_failed`, note `refinement_not_converged`); a refinement that changed to a non-rankable status leaves the ranking entirely with a recorded reason (`refinement_changed_status`); - the refined set is re-deduplicated with the section 9.3 rule through a scratch registry, and a merged entry keeps the summed hit counts, the union of replicas and the earliest first-found record; - ranking and export directories follow the **refined** energy, so `top/rank_001` is the lowest refined structure; - refined and unrefined energies are never interleaved: each table has its own best energy, the export window is relative to the refined best, and `ranking.best_energy_source` says which table the reported best came from. Engine (spec 7.3): - abort frames are never quenched: the observer checks the integrity *before* keeping a snapshot, the force abort raises before the snapshot is kept, and the `except` clause no longer appends the abort frame, so an integrity-abort frame is not quenched twice; - the end-of-cycle frame gets the same early integrity check as the hold-phase snapshots; - `quench()` no longer lets a calculator that raises on a bad geometry escape as an uncaught exception; the outcome is `quench_failed`. Diagnostics (spec 10.2/10.4): - `top_k_never_reached_by_start_quench` now means "no *member* has a start origin" (merged refined entries are checked through all their source ids); - `first_found_fraction` and `best_first_found_fraction` use the unique's `first_found_quench_index`, not the representative's own quench index. Outputs (spec 11.1): - `minima/all_minima.extxyz` now holds every quench result of every status with its provenance (unique id, record id, status, flags, energy, fmax, steps, quench index, cumulative MD ps, origin), and `minima/registry.json` holds the registry. Non-finite energies are omitted from the frame info because extxyz cannot carry NaN. Tests: `tests/mliport/mliport/confsearch/test_refinement.py` (6 tests) covers reordering, merging, unconverged refinement, status change, the minima directory and the member-based diagnostics. Full confsearch suite on CPU: 132 passed. DATA IMPACT: no scientific record invalidated. Ranking/export ordering and the `minima/` contents change; runs are re-ranked from their stored quench results.
3afc7e7 to
0c01dc1
Compare
…puts (spec rev 5 §10/§11.1) Tracking: #61 (spec revision 5, PR #64 review) Addresses all six review items on #64. Ranking and refinement (spec 10.1/10.3): - a refinement replaces the quench result only when it converged **and** its classification is still rankable; an unconverged refinement keeps the quench result and is flagged (`refinement_failed`, note `refinement_not_converged`); a refinement that changed to a non-rankable status leaves the ranking entirely with a recorded reason (`refinement_changed_status`); - the refined set is re-deduplicated with the section 9.3 rule through a scratch registry, and a merged entry keeps the summed hit counts, the union of replicas and the earliest first-found record; - ranking and export directories follow the **refined** energy, so `top/rank_001` is the lowest refined structure; - refined and unrefined energies are never interleaved: each table has its own best energy, the export window is relative to the refined best, and `ranking.best_energy_source` says which table the reported best came from. Engine (spec 7.3): - abort frames are never quenched: the observer checks the integrity *before* keeping a snapshot, the force abort raises before the snapshot is kept, and the `except` clause no longer appends the abort frame, so an integrity-abort frame is not quenched twice; - the end-of-cycle frame gets the same early integrity check as the hold-phase snapshots; - `quench()` no longer lets a calculator that raises on a bad geometry escape as an uncaught exception; the outcome is `quench_failed`. Diagnostics (spec 10.2/10.4): - `top_k_never_reached_by_start_quench` now means "no *member* has a start origin" (merged refined entries are checked through all their source ids); - `first_found_fraction` and `best_first_found_fraction` use the unique's `first_found_quench_index`, not the representative's own quench index. Outputs (spec 11.1): - `minima/all_minima.extxyz` now holds every quench result of every status with its provenance (unique id, record id, status, flags, energy, fmax, steps, quench index, cumulative MD ps, origin), and `minima/registry.json` holds the registry. Non-finite energies are omitted from the frame info because extxyz cannot carry NaN. Tests: `tests/mliport/mliport/confsearch/test_refinement.py` (6 tests) covers reordering, merging, unconverged refinement, status change, the minima directory and the member-based diagnostics. Full confsearch suite on CPU: 132 passed. DATA IMPACT: no scientific record invalidated. Ranking/export ordering and the `minima/` contents change; runs are re-ranked from their stored quench results.
72bf8ee to
1079eef
Compare
…puts (spec rev 5 §10/§11.1) Tracking: #61 (spec revision 5, PR #64 review) Addresses all six review items on #64. Ranking and refinement (spec 10.1/10.3): - a refinement replaces the quench result only when it converged **and** its classification is still rankable; an unconverged refinement keeps the quench result and is flagged (`refinement_failed`, note `refinement_not_converged`); a refinement that changed to a non-rankable status leaves the ranking entirely with a recorded reason (`refinement_changed_status`); - the refined set is re-deduplicated with the section 9.3 rule through a scratch registry, and a merged entry keeps the summed hit counts, the union of replicas and the earliest first-found record; - ranking and export directories follow the **refined** energy, so `top/rank_001` is the lowest refined structure; - refined and unrefined energies are never interleaved: each table has its own best energy, the export window is relative to the refined best, and `ranking.best_energy_source` says which table the reported best came from. Engine (spec 7.3): - abort frames are never quenched: the observer checks the integrity *before* keeping a snapshot, the force abort raises before the snapshot is kept, and the `except` clause no longer appends the abort frame, so an integrity-abort frame is not quenched twice; - the end-of-cycle frame gets the same early integrity check as the hold-phase snapshots; - `quench()` no longer lets a calculator that raises on a bad geometry escape as an uncaught exception; the outcome is `quench_failed`. Diagnostics (spec 10.2/10.4): - `top_k_never_reached_by_start_quench` now means "no *member* has a start origin" (merged refined entries are checked through all their source ids); - `first_found_fraction` and `best_first_found_fraction` use the unique's `first_found_quench_index`, not the representative's own quench index. Outputs (spec 11.1): - `minima/all_minima.extxyz` now holds every quench result of every status with its provenance (unique id, record id, status, flags, energy, fmax, steps, quench index, cumulative MD ps, origin), and `minima/registry.json` holds the registry. Non-finite energies are omitted from the frame info because extxyz cannot carry NaN. Tests: `tests/mliport/mliport/confsearch/test_refinement.py` (6 tests) covers reordering, merging, unconverged refinement, status change, the minima directory and the member-based diagnostics. Full confsearch suite on CPU: 132 passed. DATA IMPACT: no scientific record invalidated. Ranking/export ordering and the `minima/` contents change; runs are re-ranked from their stored quench results.
0c01dc1 to
6e6007a
Compare
hydrogen1222
left a comment
There was a problem hiding this comment.
Second review (spec rev 6) — P2: one should-fix
Items 1–6 of the first review are resolved: refinement only replaces a quench result when converged and still rankable, refined set re-deduplicated, ranking/exports by refined energy, no interleaving, abort frames no longer quenched, end-of-cycle integrity check, quench() robust, member-based baseline, first-found fraction, minima/ outputs. Good tests.
Remaining (spec rev 6 §10.3):
- When the refined table is non-empty, exports come only from it (
results.py~L674). A candidate inside the refinement window whose refinement did not converge (likely for floppy chains at fmax 0.02) is then not exported at all — possibly the lowest quench minimum — and only arefinement_notesentry records it. That is the "silent deletion" failure mode §9.3 warns about. Export such candidates astop/unrefined_NNN/(quench geometry/energy, flagged) and add a warning naming them. _dedup_refined(L284) copiesflagsfrom the quench representative; after refinement the classification (chemisorbed/physisorbed, far-field flag) can differ. Useoutcome.classification.flags.
🤖 Generated with Claude Code
Generated by Claude Code
Tracking: #61 (spec revision 6, second review of PR #63) `place_molecule` computed `anchor_partner_indices(slab, options)` before it knew whether an anchor had been requested, so **contact** placement on a slab without non-ionic atoms (a Li-metal surface) was refused with an anchored-placement error. The partner set is now computed only when `cs_place_anchor` selects an anchor (the objective and the final check assert it is present), which keeps the revision 5 semantics for anchored starts. Test: contact placement of OH on an all-Li slab succeeds, reports no anchor, and still satisfies the contact rule (min q = cs_place_contact_scale to 1e-3). DATA IMPACT: no scientific record invalidated. Anchored placement is unchanged; contact placement on all-ionic slabs now works instead of failing closed. Placement suite on CPU: 20 passed.
…ts (P2) Tracking: #61 (spec revision 4, phase P2) Part of the MD-based configuration search feature. What was missing: P1 had no way to run a search - no MD cycles, no quench pipeline, no Metropolis, no checkpointing and no results. What this adds: - quench.py: fixed-cell FIRE on R with only FixAtoms, per-step finite/force gates, quench_failed / quench_not_converged as outcomes, and refine(). - engine.py: the section 7.1 schedule (start quench -> round-robin cycles -> consolidation -> refinement -> ranking), the section 7.2 mobile sets, the section 7.3 cycle (Maxwell-Boltzmann over the mobile DOF with zero fixed momenta, Langevin hold, linear cool ramp with set_temperature every cs_ramp_interval, snapshot frames, per-step safety, early integrity abort, end-of-cycle Metropolis with the uniform draw taken every eligible proposal), the section 7.5 SeedSequence streams, raw/replica_RRR/cycle_CCC output through AsyncMDOutputWriter (unchanged MD_CSV_HEADER) and cycle.json, and the section 7.1 failed_start handling. - checkpoint.py: atomic JSON checkpoints after every unit, resume fingerprint (version, revisions, model, input hashes, regions, seed, every option except output/verbosity), key-level diffing on refusal, and incomplete-attempt archiving that never deletes raw files. - results.py: discovery.csv, saturation diagnostics ("lowest found", never "global minimum"), baseline vs search, the section 8.5 warnings, top-K refinement, ranking in separate refined/unrefined tables, artifacts.json and the section 10.5 exports (POSCAR with selective dynamics, structure.extxyz, cp2k_coord.xyz, cp2k_cell.inc, cp2k_fixed_atoms.inc, minimum.json) with the slab wrapped and the adsorbate made whole under MIC. Tests (spec 13.1/13.2): test-only synthetic calculators (egg-crate with three known sites and exactly known energies, shallow-Morse bond breaking, direct force, non-finite) plus end-to-end tests that the search finds every known minimum to 1e-6 eV, that same-basin quenches merge through G, that fixed atoms never move, that the temperature ramp is the documented linear schedule, that force/non-finite/integrity aborts are recorded and the search continues, that two runs with one seed are identical, that an interrupted run resumed from its checkpoint reproduces the uninterrupted ranking exactly, and that exports re-read equal to the minimum up to lattice translations. DATA IMPACT: no scientific record invalidated. New outputs only. Full suite on CPU: 1569 passed, 33 skipped.
…6 §10.3) Tracking: #61 (spec revision 6, second review of PR #64) - A candidate inside the refinement window whose refinement did not converge is no longer dropped from the DFT deliverable: it is exported as `top/unrefined_NNN/` with its **quench** geometry and energy (flagged `refined: false`, `refinement_failed: true` in `artifacts.json`), next to the refined ranks, and a warning names it. This is the "silent deletion" failure mode section 9.3 warns about: a floppy chain that cannot reach 0.02 eV/A may still be the lowest quench minimum. - A refined entry's `flags` now come from the **refined** classification instead of the quench representative (chemisorbed/physisorbed and the far-field slab flag can change during refinement). Tests: two new cases in `test_refinement.py` (the failed-refinement candidate is exported with its quench energy/geometry and produces a warning; the refined entry's flags follow the refined classification). DATA IMPACT: no scientific record invalidated. Exports gain candidates that were previously missing; ranking order and energies are unchanged. Confsearch suite on CPU: 134 passed.
6e6007a to
1682d92
Compare
…nto P2 #63 was merged with 'Rebase and merge', which rewrote the P1 commits on main. Their content is byte-identical to this branch's P1 base (41102c7), so this merge keeps the branch tree unchanged and only records main as a parent, which removes the add/add conflicts GitHub reported on #64. DATA IMPACT: no scientific record invalidated (no file content changes). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017vVRW3uEnhYKFinpvqMysi
Tracking: #61
Implements spec revision 4, phase P2.
What this does
Adds the search engine:
quench.py: fixed-cell FIRE on R with onlyFixAtoms, per-step finite andraw-force gates,
quench_failed/quench_not_convergedas outcomes, andrefine().engine.py: the section 7.1 schedule (start quench -> round-robin cycles ->consolidation -> refinement -> ranking), section 7.2 mobile sets, the section
7.3 cycle (Maxwell-Boltzmann over the mobile DOF with zero fixed momenta,
Langevin hold, linear cool ramp with
set_temperatureeverycs_ramp_interval, snapshot frames, per-step safety, early integrity abort,end-of-cycle Metropolis with the uniform draw taken every eligible proposal),
section 7.5
SeedSequencestreams, rawraw/replica_RRR/cycle_CCC/outputthrough
AsyncMDOutputWriterwith the unchangedMD_CSV_HEADERpluscycle.json, and the section 7.1failed_starthandling.checkpoint.py: atomic JSON checkpoints after every unit, the resumefingerprint (version, revisions, model, input hashes, regions, seed, every
option except output/verbosity), key-level diffing on refusal, and
incomplete-attempt archiving that never deletes raw files.
results.py:diagnostics/discovery.csv, saturation diagnostics ("lowestfound", never "global minimum"), baseline vs search, the section 8.5
warnings, top-K refinement, ranking in separate refined/unrefined tables,
artifacts.jsonand the section 10.5 exports (POSCAR with selective dynamics,structure.extxyz,cp2k_coord.xyz,cp2k_cell.inc,cp2k_fixed_atoms.inc,minimum.json) with the slab wrapped and theadsorbate made whole under MIC.
What it does NOT do yet
with hand-built
PreparedStartobjects.extend/merge/queue/TUI (P4/P5).campaign is P5.
Tests run and results
1569 passed, 33 skipped;tests/mliport/mliport/confsearch/test_engine.pyis 14 tests.
same-basin quenches merged through
G, fixed atoms never move, thetemperature ramp equals the documented linear schedule, force / non-finite /
integrity aborts are recorded and the search continues.
interrupted run resumed from its checkpoint reproduces the uninterrupted
ranking exactly; exports re-read equal to the minimum up to lattice
translations.
Deviations from spec
build_resultsmarks a runfailedonly when it had replicas and nonesurvived (a merge has none), which matches section 7.1 but is stricter than
"no surviving replica" read literally.
nullfor that minimum's measureddistances (JSON has no NaN) instead of a NaN sentinel.
phase = hold|cool; thetarget-temperature schedule is recorded in
cycle.json, as specified.(checkpoint
from_dict, fingerprint recomputation on resume, NaN handling),so those fixes were red-first; the initial engine skeleton and the results/
exports module were implemented and then covered by the same commit's tests.
Revision 5 follow-up (review of this PR)
result only when it converged and its status is still rankable. An
unconverged refinement keeps the quench result and is flagged; a refinement
that changed to a non-rankable status leaves the ranking with a recorded
reason. The refined set is re-deduplicated with the §9.3 rule (merged entries
keep the summed hit counts, the union of replicas and the earliest
first-found record), ranking and
top/rank_001follow the refined energy,and refined/unrefined energies are never interleaved (each table has its own
best;
ranking.best_energy_sourcesays which).a snapshot is kept, the force abort raises before the snapshot is kept, and
the
exceptclause no longer appends the abort frame, so an integrity-abortframe is not quenched twice; the end-of-cycle frame gets the same integrity
check.
quench()cannot crash the search: a calculator that raises on a badgeometry yields
quench_failed.top_k_never_reached_by_start_quenchmeans "no member hasa start origin";
first_found_fractionusesfirst_found_quench_index.minima/all_minima.extxyzholds every quench resultof every status with provenance, and
minima/registry.jsonholds the registry.tests/mliport/mliport/confsearch/test_refinement.py(6 tests) coversreordering, merging, unconverged refinement, status change, the minima
directory and the member-based diagnostics.
Full suite on CPU (rebased stack): 1632 passed, 33 skipped; lint/format and
the repository hygiene check clean; CI green.
Revision 6 follow-up (second review of this PR)
§10.3). It is written as
top/unrefined_NNN/with its quench geometry andenergy, flagged (
refined: false,refinement_failed: trueinartifacts.json), next to the refined ranks, and a warning names it. Thiscloses the "silent deletion" failure mode §9.3 warns about: a floppy chain that
cannot reach 0.02 eV/A may still be the lowest quench minimum.
quench representative (chemisorbed/physisorbed and the far-field slab flag can
change during refinement).
test_refinement.py(the failed-refinement candidateis exported with its quench energy/geometry and produces a warning; the refined
entry's flags follow the refined classification).
Full suite on CPU: 1639 passed, 33 skipped; lint/format/hygiene clean; CI
green.